Skip to main content

Workflow Modules — Authoring & Testing

This page is the authoritative implementation-grade guide for adding workflow modules in ValkyrAI. It is derived from internal design docs and converted into tight public documentation.

1) Module authoring contract​

A. Code location​

  • valkyrai/src/main/java/com/valkyrlabs/workflow/modules/
  • Prefer grouping by capability namespace (api, email, storage, etc.)

B. Nominal behavior​

  • Extend VModule
  • Annotate with @Component("moduleId") and @VModuleAware
  • Override:
    • Map<String, Object> execute(Workflow workflow, Task task, ExecModule module, Map<String, Object> input)
  • Return a serializable Map for workflow state mapping
  • Catch every exception, and return structured error payloads instead of throwing

C. Config metadata​

  • All user-configurable inputs must be explicit
  • @ConfigParam metadata should include label, description, required, default, and validation rules
  • Maintain backwards-compatible config keys

D. Output contract​

  • Stable output shape
  • Explicit status field (success, error, warning)
  • Actionable error fields: code, message, context
  • Avoid “partial success” as the default semantics unless clearly documented

E. Failure semantics​

  • Detect invalid config early
  • Return machine-readable payload with human-friendly message
  • Log full context in server logs (taskId, workflowId, moduleId)
  • Do not swallow exceptions silently

2) Determinism checklist (pre-merge)​

  • Same config + same input => same output table
  • External dependencies are injected/abstracted for tests
  • Side effects don't execute before validation
  • Errors are machine-readable and actionable

3) Tests (minimum bar)​

Unit tests​

Add tests in valkyrai/src/test/java/com/valkyrlabs/workflow/modules/*

Required coverage for each module:

  1. Happy path
  2. Validation failures
  3. External dependency failures
  4. Determinism / repeat-lock behavior

Engine integration tests​

Update or add focused tests in:

  • WorkflowExecutionServiceTest
  • ModuleOrderServiceTest

Local command​

mvn -pl valkyrai -Dtest=WorkflowExecutionServiceTest,ModuleOrderServiceTest test
mvn -pl valkyrai -Dtest=<YourModuleTestClass> test

4) Merge-slice guidance​

  1. Metadata + validation first
  2. Happy-path functionality next
  3. Failure handling + observability
  4. Docs + tests